feat(citations): add Org 9.5 citation support with BibTeX source, completions, and go-to-source by NickHu · Pull Request #1113 · nvim-orgmode/orgmode

NickHu · 2026-03-10T19:31:48Z

Summary

This PR adds support for Citations, introduced by orgmode 9.5.

Related Issues

Depends on nvim-orgmode/tree-sitter-org#7 (this is why the tests fail)

Closes #718

Changes

lua/orgmode/org/citations/init.lua — OrgCitations class: registers sources, aggregates get_items(), dispatches follow(key), and resolves the citation key at cursor via tree-sitter citation_reference node
lua/orgmode/org/citations/bibtex.lua — built-in OrgCitationBibtex source; parses .bib files (mtime-cached), resolves paths from citations.org_cite_global_bibliography config and file-local #+bibliography: directives, implements follow(key) to open the file at the entry line
lua/orgmode/org/autocompletion/sources/citations.lua — omnifunc completion source; matches [cite:@ / [cite/style:@ prefix and returns keys from all registered sources
lua/orgmode/config/defaults.lua — adds citations.org_cite_global_bibliography and citations.sources defaults
lua/orgmode/colors/highlighter/markup/citation.lua + queries/org/markup.scm — syntax highlighting for citation nodes
lua/orgmode/org/mappings.lua — org_open_at_point now delegates to citations:follow() when on a citation key
docs/configuration.org — new Citations section covering syntax, bibliography config, custom source API, and Zotero Local API example

Checklist

I confirm that I have:

Followed the
Conventional Commits
specification (e.g., feat: add new feature, fix: correct bug,
docs: update documentation).
My PR title also follows the conventional commits specification.
Updated relevant documentation, if necessary.
Thoroughly tested my changes.
Added tests (if applicable) and verified existing tests pass with
make test.
Checked for breaking changes and documented them, if any.

Warning

The bulk of this PR is AI-generated, although I have combed over it extensively and cleaned it up by hand and fixed things.
It is basically exactly the changes you would expect to see from the PR title, except for the following design considerations:

citation sources are extensible; this is to facilitate populating them from outside a bibtex file (e.g. Zotero library which is given as an example in the documentation);
lua/orgmode/org/citations/_meta.lua adds two fields label and description to OrgCitationItem, which currently aren't used anywhere; the hope is that these items can be utilised in the completion popup, but it seems like support for ancillary information in completion items is not fleshed out in nvim-orgmode yet as a whole. The intended use-case is so that the completion call/popup can show or react to something like Doe, John 2026 Some Article (label) while still completing the key @doe2026, and LSP hover can display extra information (like an article abstract) from the description field.

I have tested it extensively, and I think it is ready for upstream review, but I am marking it as draft for the above reasons.

kristijanhusak · 2026-03-11T19:09:21Z

I created a new release of the TS parser (https://github.com/nvim-orgmode/tree-sitter-org/releases/tag/2.0.3).
Let's update the required_version to 2.0.3 and see how it looks.

…pletions, and go-to-source

…mple

NickHu · 2026-03-11T23:39:06Z

@kristijanhusak rebased onto master and tests passing

Copilot

Pull request overview

Adds Org mode 9.5 citation support to the Neovim orgmode plugin, including BibTeX-backed key discovery, omnifunc completion, syntax highlighting, and “go to bibliography entry” behavior via the existing org_open_at_point mapping.

Changes:

Introduces a new OrgCitations subsystem with a built-in BibTeX source and extensible custom source API.
Adds citation key omnifunc completion plus #+bibliography directive completion.
Adds citation highlighting, documentation, tests/fixtures, and bumps the required tree-sitter-org grammar version.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`lua/orgmode/org/citations/init.lua`	New citations manager (source registration, item aggregation, follow, at-cursor resolution).
`lua/orgmode/org/citations/bibtex.lua`	Built-in BibTeX citation source (path discovery, parsing, mtime caching, follow-to-entry).
`lua/orgmode/org/citations/_meta.lua`	Type metadata for citation items/sources.
`lua/orgmode/org/autocompletion/sources/citations.lua`	Omnifunc completion source for citation keys inside `[cite...]`.
`lua/orgmode/org/autocompletion/sources/directives.lua`	Adds `#+bibliography` to directive completions.
`lua/orgmode/org/autocompletion/init.lua`	Wires citations into completion and registers the new completion source.
`lua/orgmode/org/mappings.lua`	Extends `org_open_at_point` to follow citation keys under cursor.
`lua/orgmode/init.lua`	Instantiates `OrgCitations` and passes it into mappings/completion.
`lua/orgmode/config/defaults.lua`	Adds default `citations` config keys (`sources`, `org_cite_global_bibliography`).
`queries/org/highlights.scm`	Adds highlight captures for citation nodes.
`lua/orgmode/colors/highlights.lua`	Maps new citation captures to existing highlight groups.
`lua/orgmode/utils/treesitter/install.lua`	Bumps required tree-sitter-org grammar version.
`docs/configuration.org`	Documents citation syntax, bibliography configuration, and custom sources (incl. Zotero example).
`tests/plenary/org/citations/citations_spec.lua`	Tests citations source registration, aggregation, and follow dispatch.
`tests/plenary/org/citations/bibtex_spec.lua`	Tests BibTeX parsing, bibliography discovery, follow behavior, and completion regex.
`tests/plenary/org/autocompletion_spec.lua`	Updates directive completion expectations for `#+bibliography`.
`tests/plenary/fixtures/citations/refs.bib`	BibTeX fixture used by tests.
`tests/plenary/fixtures/citations/extra.bib`	Additional BibTeX fixture used by tests.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

+  if raw:sub(1, 1) ~= '/' then
+    local base = base_dir or vim.fn.getcwd()
+    return vim.fn.fnamemodify(base .. '/' .. raw, ':p')
+  end


+      local file = self.files:load_file_sync(current_filename)
+      if file then
+        local file_dir = vim.fn.fnamemodify(file.filename, ':p:h')
+        local directives = file:_get_directive('bibliography', true)
+        if directives then
+          if type(directives) == 'string' then
+            directives = { directives }
+          end
+          for _, raw in ipairs(directives) do
+            add(raw, file_dir)
+          end


+--- Build a simple in-memory citation source for testing.
+---@param name string
+---@param items OrgCitationItem[]
+---@param follow_handler? fun(key: string): boolean


+  for i, source in ipairs(config.citations.sources) do
+    if type(source.get_name) == 'function' then
+      self:add_source(source)
+    else
+      vim.notify(('Citation source at index %d must have a get_name method'):format(i), vim.log.levels.ERROR)


+local function parse_file(path)
+  local stat = vim.uv.fs_stat(path)
+  if not stat then
+    return {}
+  end
+  local mtime_sec = stat.mtime.sec
+  local cached = _cache[path]
+  if cached and cached.mtime_sec == mtime_sec then
+    return cached.items
+  end
+  local lines = vim.fn.readfile(path)
+  local items = parse_bibtex(table.concat(lines, '\n'))
+  _cache[path] = { mtime_sec = mtime_sec, items = items }
+  return items


kristijanhusak

Sorry for the late review. Overall it seems to be working fine. I'd just like to refactor few things before we merge it in.

kristijanhusak · 2026-05-03T14:00:06Z

    return self:_jump_to_footnote(footnote)
  end
+
+  if self.citations then


Why do we need this check?

kristijanhusak · 2026-05-03T14:07:41Z

  },
+  citations = {
+    sources = {},
+    org_cite_global_bibliography = {},


Let's move this to the top level config as other things to make it consistent. Sources configuration can stay like this.

kristijanhusak · 2026-05-03T14:12:35Z

+---@param raw string
+---@param base_dir? string
+---@return string
+local function resolve_path(raw, base_dir)


We can use get_real_path from utils.fs.lua instead of this function.

kristijanhusak · 2026-05-03T14:14:35Z

@@ -0,0 +1,155 @@
+local config = require('orgmode.config')


Since we also support custom sources with this PR, we can create an org/citations/sources folder and put this there. I see that Emacs orgmode also supports json format so we can also add that as a built in.

kristijanhusak · 2026-05-03T14:17:12Z

+      local file = self.files:load_file_sync(current_filename)
+      if file then
+        local file_dir = vim.fn.fnamemodify(file.filename, ':p:h')
+        local directives = file:_get_directive('bibliography', true)


Let's not use private methods outside of the file. Add a public method file:get_bibliography and do this inside.

Suggested change

local directives = file:_get_directive('bibliography', true)

local directives = file:get_bibliography()

kristijanhusak · 2026-05-03T14:21:30Z

+  if cached and cached.mtime_sec == mtime_sec then
+    return cached.items
+  end
+  local lines = vim.fn.readfile(path)


We should use async file reading whenever possible. Look into utils.readfile. This would require refactoring few things to be async, but shouldn't be big of a problem.

Also, what Copilot mentioned below, try using nsec when available. When it is not available, nsec is 0, so you need to fallback to sec. You can check how it's done in files/file.lua.

kristijanhusak · 2026-05-03T14:24:16Z

+    end
+  end
+
+  if self.files then


We can default self.files to empty table in the new() so there's no need to do these kind of checks.

NickHu force-pushed the citations branch from 4b12bc0 to cd1e8f1 Compare March 10, 2026 19:34

Copilot AI and others added 3 commits March 11, 2026 23:30

feat(citations): add Org 9.5 citation support with BibTeX source, com…

aa17241

…pletions, and go-to-source

docs: use plenary.curl instead of pcall in zotero citation source exa…

a579ee2

…mple

fix: update required treesitter parser version to 2.0.3

5845c99

NickHu force-pushed the citations branch from 0139669 to 5845c99 Compare March 11, 2026 23:32

fix: autocomplete test completes #+bibliography

64c0ecc

NickHu marked this pull request as ready for review March 14, 2026 01:35

Copilot AI review requested due to automatic review settings March 14, 2026 01:35

Copilot started reviewing on behalf of NickHu March 14, 2026 01:35 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

Merge branch 'master' into citations

d6d6ee8

kristijanhusak requested changes May 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(citations): add Org 9.5 citation support with BibTeX source, completions, and go-to-source#1113

feat(citations): add Org 9.5 citation support with BibTeX source, completions, and go-to-source#1113
NickHu wants to merge 5 commits into
nvim-orgmode:masterfrom
NickHu:citations

NickHu commented Mar 10, 2026 •

edited

Loading

Uh oh!

kristijanhusak commented Mar 11, 2026

Uh oh!

NickHu commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

kristijanhusak left a comment

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

kristijanhusak May 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	local directives = file:_get_directive('bibliography', true)
	local directives = file:get_bibliography()

Uh oh!

Conversation

NickHu commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issues

Changes

Checklist

Warning

Uh oh!

kristijanhusak commented Mar 11, 2026

Uh oh!

NickHu commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

kristijanhusak left a comment

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

kristijanhusak May 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

NickHu commented Mar 10, 2026 •

edited

Loading